ARS Configuration File Keywords

Services > Service Configuration Files > Service Configuration File Keywords > ARS Configuration File Keywords

ARS Configuration File Keywords

For more information about modifying the ARS configuration file, see Service Configuration Files.

The ARS keywords are listed in the tables below:

Service Info Keywords
Logging Keywords
Security Keywords
Backup Keywords
Auditing Keywords
Metering Keywords

Note: An asterisk in the Options column ( * ) denotes a user-defined option.

Service Info Keywords

Keyword	Required	Description	Default	Options
SERVICE	Yes	The name of the service in Site.Service format.	SITE.ARS	8 chars max each for site and service name; no spaces; must be unique to the system. Valid characters are: A-Z, 0-9, !, $, _
ACS	Yes	The Site and Service name of the service’s ACS, in Site.Service format.	SITE.ACS	Any valid ACS name.
LICENSE_MASTER	No	Sets this ARS to be in control of the license file. The License Master pushes license information and the time to all other ARSs on the domain. Only one ARS on a domain can be the license master.	No	YES, NO
ELS	No	The Site and Service name of the service’s ELS, in Site.Service format.	SITE.ELS	Any valid ELS name.
MSS	Yes	The Site and Service name of the MSS service from which commands will be accepted, in Site.Service format.	SITE.MSS	Any valid MSS name.
AUD	No	The Site and Service name of the service’s AUD, in Site.Service format. Note: For a redundant environment, if the AUD service listed in the Ars.cfg does not specify a domain ID, then any AUD services of that name on all domains within the redundancy definition will receive audit entries from that ARS because it isn’t a unique identity. By specifying the domain ID for the AUD in the config file you can limit audit entries to just that individual service. Note that replicating AUD services won't accept entries from sources other than the replicated AUD.	SITE.AUD or [DOMAIN]SITE.AUD	Any valid AUD name.
ACCEPT_TIME_SYNC	No	This keyword periodically sets the computer time for the current ARS to the computer time of the License Master. Set this keyword to YES to periodically synchronize the computer time of this ARS with that of the License Master. Set this keyword to NO to synchronize computer time only if there is a delta of 10 seconds or more between the subordinate ARS and the master.	YES	YES, NO
REDUNDANT	No	Indicates whether Redundancy is enabled for this service and it is part of a redundant set with other services. Set to TRUE to enable Redundancy for this service and indicate that it is in a redundant relationship with another service within the redundancy environment. Set to FALSE or commented out to disable Redundancy for this service. See Redundancy for more configuration details. A redundancy definition for your CygNet environment is configured in the CygNet Redundancy Editor. Note: A redundant RSM cannot be managed by another RSM in your redundancy environment. CygNet won’t allow an RSM to start an owned RSM if that RSM has the REDUNDANT keyword set to TRUE. The IN_REDUNDANT_SET (Service in redundant set) info item will report whether this service is part of a redundant relationship.	FALSE	TRUE, FALSE
WAIT_TIME_FOR_FIRST_SYNC	No	Specifies the number of seconds to delay the startup of the ARS, so that the service can synchronize with other ARS services on the same domain. Setting this keyword may prevent multiple services starting up and running on the same domain for a short time after a hard failover.	0	For services in a redundant environment we recommend you start with a value of 30, then consider adjusting as needed. For non-redundant services, we recommend you leave the value at zero.
ADDITIONAL_DOMAINS	No	An optional keyword that specifies up to ten additional domains on which this ARS can run. Allowing an ARS to run on several domains will reduce the overhead of managing multiple RSM and ARS services in a complex redundant environment. Service shutdown and startup delay time will be reduced, as the last ARS in a failover event will continue to run after a local or data-center failover has occurred. Other systemic benefits include improved management by a single ARS in a failover set of the CAL, host activation, and other license-master-controlled entities (CvsMetadata, license master, CygNet time zones). The ADDITIONAL_DOMAINS keyword is not required if you’re using CygNet Redundancy and the ARS is marked as REDUNDANT in its config file.		Up to 10 domain IDs, space delimited.

Logging Keywords

Keyword	Required	Description	Default	Options
LOGMASK_ELS	Yes	Specifies the types of service events to be logged to the associated ELS (specified in the ELS keyword). To disable logging to the ELS, comment out the ELS keyword for the selected service. See the Note below this table for more information about the keyword values. See LOGMASK_ELS in the Logging section of this Help for more information. The LOGMASK_ELS ( LMask ELS) info item will report the value of this keyword.	CONTROL EXCEPTIONS	LOG_ALL or any combination of: CONTROL EXCEPTIONS WARNING PROG_STAT MIN_TRACE
LOGMASK_FILE	Yes	Specifies the type(s) of service events to be logged to the service’s log file ([file name].log). During the current session of the service, data is written to the current log file. Log file names follow the naming convention of the selected logging mode (as set by the LOGFILE_MODE keyword value). See the Note below this table for more information about the keyword values. See LOGMASK_FILE in the Logging section of this Help for more information. The LOGMASK_FILE (LMask File) info item will report the value of this keyword.	CONTROL EXCEPTIONS WARNING	LOG_ALL or any combination of: CONTROL EXCEPTIONS WARNING PROG_STAT MIN_TRACE MAX_TRACE ENTER_EXIT
LOGFILE_FILE_COUNT	Yes	Specifies the maximum number of log files that a service will create before it starts re-using log files. For example, a count of two will produce SVC001.log, then SVC002.log, and then start back at SVC001.log, where SVC is the name of the service. Specify any value from 2 to 100. See LOGFILE_FILE_COUNT in the Logging section of this Help for more information. The LOGFILE_FILE_COUNT (File Cnt) info item will report the value of this keyword.	2	2 to 100
LOGFILE_LINE_COUNT	Yes	When the value of the LOGFILE_LIMIT_MODE keyword is LINE, this keyword specifies the maximum number of lines per log file. When the specified line count is reached, the log file is truncated at the limit point, and logging is resumed using the next available log file. Specify any value from 1000 to 1000000. See LOGFILE_LINE_COUNT in the Logging section of this Help for more information. The LOGFILE_LINE_COUNT (Line Cnt) info item will report the value of this keyword.	100000	1000 to 1000000
LOGFILE_MODE	Yes	Specifies the operational mode for the log file, that is, how log files are maintained. Options are LEGACY or EXTENDED. The default value is LEGACY. See LOGFILE_MODE in the Logging section of this Help for more information. The LOGFILE_MODE (Logging Mode) info item will report the value of this keyword.	LEGACY	EXTENDED LEGACY
LOGFILE_LIMIT_MODE	Yes	Specifies how to limit the size of each individual log file. Options are LINE (maximum line count is determined by the LOGFILE_LINE_COUNT keyword) or SIZE (maximum file size in megabytes) determined by the LOGFILE_FILE_SIZE keyword). The default value is LINE. See LOGFILE_LIMIT_MODE in the Logging section of this Help for more information. The LOGFILE_LIMIT_MODE (Limit Mode) info item will report the value of this keyword.	LINE	LINE SIZE
LOGFILE_FILE_SIZE	Yes	When the value of the LOGFILE_LIMIT_MODE keyword is set to SIZE, this keyword specifies the maximum size (in megabytes) allowed for a log file, before logging will be continued using the next log file. Possible maximum size values are user-determined, respecting the limits of your specific system configuration. The default value is 100 megabytes. When the specified limit is reached, the log finishes the current line, closes the current file, and then continues logging in the next available log file. See LOGFILE_FILE_SIZE in the Logging section of this Help for more information. The LOGFILE_FILE_SIZE (File Size) info item will report the value of this keyword.	100 megabytes	Depends on user system configuration

Note: Use the following keyword values to set logging options for the LOGMASK_ keywords.

LOG_ALL - logs all options. This is the highest level of logging and will log everything the service is programmed to log.
CONTROL - logs control operations, such as startups, shutdowns and UIS operational events, etc.
ENTER_EXIT - logs every entry and exit through functions. This is used primarily by a programmer to debug code, and is too verbose for the ELS (not applicable for LOGMASK_ELS).
EXCEPTIONS - logs all exceptions thrown, not all of which are severe. An exception is an unexpected event occurring during execution of the service. It could be the result of a configuration error, an invalid command parameter, a bug, etc.
MAX_TRACE - more verbose logging than MIN_TRACE. This is used primarily by a programmer to debug code, and is too verbose for the ELS (not applicable for LOGMASK_ELS).
MIN_TRACE - used primarily by a programmer to debug code.
PROG_STAT - typically used to monitor the progress of the code through some logical steps. Some services, like the GNS, use it to add to the logging of the notifications, acknowledgments, and operations.
STATISTICS - enables gathering and reporting of message processing statistics.
WARNING - logs anomalies, not as serious as exceptions.

Example

A value for LOGMASK_ELS might be CONTROL + EXCEPTIONS.

A value for LOGMASK_FILE might be CONTROL + EXCEPTIONS + WARNING + PROG_STAT.

Security Keywords

Keyword	Required	Description	Default	Options
ACS_ID	Yes	The User ID of the service. This keyword is required for performing security events.	ARS	*

Backup Keywords

Keyword	Required	Description	Default	Options
BACKUP_PATH	No	Specifies the path to the backup directory for the service files. The path can be relative or absolute. If the path contains spaces it must be enclosed in quotation marks. The service will create the backup folder if it does not exist. Use the Config File Manager to automatically configure this keyword for all services in your CygNet environment.	None	* (path)
BACKUP_TIME	No	Specifies the time for the daily backup to run (24-hour format 0000 to 2359, do not use a colon). If this keyword is not enabled for a service or no time is specified, the automatic backup will not occur. Service backup will only occur if manually initiated or scheduled via the MSS. Use the Config File Manager to automatically configure this keyword for all services in your CygNet environment.	None	0000 to 2359
COPY_BACKUP_TO	No	Enables copying of the backup service files to the specified directory once the backup process is complete. The path can be relative or absolute. If the directory does not exist the service will create it. If the path or directory name contains spaces, the parameter must be enclosed in quotation marks. If you specify a network drive and are running the CygNet services as system services, you must use the Universal Naming Convention (UNC) (\\Workstation\Path) to specify the path. The backup file can be copied to a network drive only if the drive is mapped to the local machine. Use the Config File Manager to automatically configure this keyword for all services in your CygNet environment.	None	* (path)

Keyword

Required

Description

Default

Options

BACKUP_PATH

Specifies the path to the backup directory for the service files. The path can be relative or absolute. If the path contains spaces it must be enclosed in quotation marks. The service will create the backup folder if it does not exist. Use the Config File Manager to automatically configure this keyword for all services in your CygNet environment.

None

* (path)

BACKUP_TIME

Specifies the time for the daily backup to run (24-hour format 0000 to 2359, do not use a colon). If this keyword is not enabled for a service or no time is specified, the automatic backup will not occur. Service backup will only occur if manually initiated or scheduled via the MSS. Use the Config File Manager to automatically configure this keyword for all services in your CygNet environment.

None

0000 to 2359

COPY_BACKUP_TO

Enables copying of the backup service files to the specified directory once the backup process is complete. The path can be relative or absolute. If the directory does not exist the service will create it. If the path or directory name contains spaces, the parameter must be enclosed in quotation marks. If you specify a network drive and are running the CygNet services as system services, you must use the Universal Naming Convention (UNC) (\\Workstation\Path) to specify the path. The backup file can be copied to a network drive only if the drive is mapped to the local machine. Use the Config File Manager to automatically configure this keyword for all services in your CygNet environment.

None

* (path)

Auditing Keywords

See ARS Audit Levels for more information.

Keyword	Required	Description	Default	Options
AUDIT_LEVEL	No	Sets auditing level of messages written to the AUD service. When set to 0, auditing is off.	1	0, 1, 2

Metering Keywords

Keyword	Required	Description	Default	Options
ARS_FORCE_CLEAN_STARTUP_METER	No	If set to YES, the ARS will not startup if an unclean ARS shutdown is detected. The MeterDbFix.exe utility* must be run manually before restarting the service. If set to NO, when an unclean ARS shutdown is detected, the MeterDbFix.exe utility* is run automatically, the service will restart, and the CygNetMeter.db file will be marked as clean. The Meter Database Fix utility (MeterDbFix.exe) is a command-line utility for clearing unclean ARS shutdowns. The utility file is stored in the CygNet\Utilities* directory on the host server.	NO	YES, NO
FORCE_METER_DB_REINDEX	No	If set to YES, forces the ARS to reindex the meter database every time it starts up. Since this option slows startup time its use is recommended only when database corruption is suspected.	NO	YES, NO
DISABLED_CAL_PURGE_AGE	No	Specifies minimum age of disabled CAL records that will be automatically deleted by the mater ARS. CAL age is number of days since last used.	712	60 to 2147483647

Keyword

Required

Description

Default

Options

ARS_FORCE_CLEAN_STARTUP_METER

If set to YES, the ARS will not startup if an unclean ARS shutdown is detected. The MeterDbFix.exe utility* must be run manually before restarting the service.

If set to NO, when an unclean ARS shutdown is detected, the MeterDbFix.exe utility* is run automatically, the service will restart, and the CygNetMeter.db file will be marked as clean.

*The Meter Database Fix utility (MeterDbFix.exe) is a command-line utility for clearing unclean ARS shutdowns. The utility file is stored in the CygNet\Utilities directory on the host server.

YES, NO

FORCE_METER_DB_REINDEX

If set to YES, forces the ARS to reindex the meter database every time it starts up. Since this option slows startup time its use is recommended only when database corruption is suspected.

YES, NO

DISABLED_CAL_PURGE_AGE

Specifies minimum age of disabled CAL records that will be automatically deleted by the mater ARS. CAL age is number of days since last used.

712

60 to 2147483647